__doc__ = """\
ChomsPy Object-Oriented Database
	License: GPLv2 (http://www.gnu.org/licenses/gpl-2.0.html)
	Copyright: G. John Schutte IV, SnohomaNET, 2008-2010
	Maintainer: G. John Schutte IV
	E-mail: john@snohoma.net
	Website: http://code.google.com/p/cognition-app-framework/


Pragmatics
	'Pragmatics' is the name of the syntax used to issue commands
		to the ChomsPy Database through the ChomsPy.DAD Module.
		
	Format: Subject(;modifier,modifier,...)/Verb/Object(;modifier,modifier,...)
	Notes: 
		The default "Grammar" is "svo" syntax, but this can be redfined. 
			Grammar Formats:
				svo = Subject/Verb/Object
				sov = Subject/Object/Verb
				vso = Verb/Subject/Object
				vos = Verb/Object/Subject
		
		There are 2 delimiters which are used to separate a Subject/Object
			from its modifiers, and modifiers from each other.  It is recommended 
			(and defaulted) to use "." for Subject/Object delimiting, and "," for
			modifiers.  See the examples below for more information.
			
	Subject:
		Subjects make up the Directory Tree where Objects are stored.
		
		Format: "Subject.modifier,modifier,(etc)"
		Translates: Subject/Modifier/Modifier/(etc)/
		Notes:
			If the Subject starts with an underscore, it is considered Private, and requires
				a user/password to read as well as write. (see Administration).
			
			When a user with write permissions Sets data into a Private Subject for the
				first time, it creates the userfile for it automatically with creating user
				as the initial level 3 administrator (see Administration).
			
	Verb:
		Verbs are the actions which are being carried out.
		
		Actions: Get, Set, List, Remove
		Notes:
			Verbs are handled differently when in Admin Mode (see Administration).
			
	Object:
		Objects are data items to be stored, or retrieved from the Database.
		Format: "Object.modifier,modifier,(etc)"
		Translates: modifier,modifier,(etc).Object

	
Schema
	Schema are not required, but can be used to make data uniform.  Schema are
		set and retrieved by passing an object without modifiers.  You can also Set
		a schema by attempting to Validate an Object while Setting it, when a schema
		does not already exist.


Administration
	__(UserDB)/Verb/(userID)
	** The double-underscore indicates "Administration Mode" **
	
	For Global Subjects:
		Global Subjects are located in the root of the ChomsPy Database, and are Public.
		
		Notes:
			The "_Admin" database is reserved for Root-level admins
		
		Commands:
			__Admin/Get/(userID) - Returns user data object.
			__Admin/Set/(userID) - Takes dictionary with user data, returns newly created user data.
			__Admin/Remove/User|Subject.(userID|SubjectID[,modifiers]) - Remove User or Subject.
	
	For Private Subjects:
		Private Subjects have their own userfiles, but operate just the same as Public Subjects otherwise.
		
		Commands:
			__Subject/Get/(userid)
			__Subject/Set/(userid)
			__Subject/Remove/User|Subject.(userID|SubjectID[,modifiers])
			
	User Levels:
		False = Invalid User - Bad login, or non-existent user
		0 = Read - Read Only
		1 = Read/Write - Read/Write Objects
		2 = Read/Write/Create - Read/Write Subjects, Objects and Remove Objects
		3 = Read/Write/Administrate - Read/Write/Remove Users, Subjects, and Objects
	
Usage
	
	################################
	# Configuration                #
	################################
	
	# Option 1: Pygmund.Id
	#	Import configuration from Id
	import Pygmund.Id as Id
	conf = Id.Init("/path/to/file.conf").Get("CHOMSPY")
	
	# Option 2: Manual Configuration
	# 	Create Dictionary with Configuration options
	conf = {
				"dbroot" : "/path/to/chomspyDB",
				"grammar" : "svo",
				"validate-objects" : true,
				"delimiters" : [ ".", "," ]
			}
	
	################################
	# To initialize a new Database #
	################################
	
	import ChomsPy.DB as DB
	
	# DB.Init(conf, user, password, initDB)
	#	initDB = Creates DB if it isn't already, and checks for proper format.
	d = DB.Init("admin", "drowssap", "/home/john/.chomspyDB", True)
	
	# Check initialization status
	print d.status
	
	##############################
	# Using the Interface Module #
	##############################
	
	import ChomsPy.DAD as DAD
	
	# DAD.Connect(conf, user, password, initDB)
	# 	initDB = Creates DB if it isn't already, and checks for proper format.
	db = DAD.Connect(conf, u, p, True)
		
	# Get Example...
	s = "News.Local,Birmingham/Get/Story.2010,08,14,143056"
	r = db.Command(s)
	
	# Set Example...
	s = "News.Local,Huntsville/Set/Story.2010,08,13,183545"
	d = { "headline" : "Criminals arrested", "author" : "A. Journalist", "body" : "filler text..." }
	r = db.Command(s,d)
	
	# Schema Examples...
		# Set a Schema
		s = "News.Local,Huntsville/Set/Story"
		d = { "headline" : "", "author" : "", body : "" }
		r = db.Command(s,d)
		
		# Set with validation against a schema
		# If no schema exists, one is created based on the data to be stored.
		s = "News.Local,Huntsville/Set/Story.2010,08,15,183555"
		d = { "headline" : "Cute Kittens save drowning Dog", "author" : "Fluff Newsman", "body" : "filler..." }
		r = db.Command(s,d,True)
		
		# Get a Schema
		s = "News.Local,Huntsville/Get/Story"
		r = db.Command(s)
	
	# List Example...
	# Get all News from August, 2010
	s = "News.Local,Huntsville/List/Story;2010,08,*"
	r = db.Command(s)
	
	# Remove Item Example...
	s = "News.Local,Huntsville/Remove/Story.2010,08,13,183545"
	r = db.Command(s)
	
	# Remove Subject Example...
	# Removes last modifier in Subject and all modifiers under it
	s = "News.Local,Birmingham/Remove/*"
	r = db.Command(s)
	
	# Administration Examples...
		# Add Global User 
		s ="__Admin/Set/john"
		d = { "password" : "drowssap", "level" : 1 }
		r = db.Command(s,d)
		
		# Create Private Subject
		s = "_Profiles/Set/john"
		d = { "email" : "john@john.com", "image" : "http://imghost.com/john.png", "bio" : "filler text" }
		r = db.Command(s,d)
		
		# Get from a Private Subject
		s = "_Profiles/Get/john"
		r = db.Command(s)
		
		# Add User to Private Subject
		s = "__Profile/Set/john"
		d = { "password" : "drowssap", "level" : 1 }
		r = db.Command(s,d)
		
		# Remove Global User 
		s = "__Admin/Remove/john"
		r = db.Command(s)

"""

__version__ = "1.0"
__copyright__ = "G. John Schutte IV (john@snohoma.net), SnohomaNET (www.snohoma.net)"
__license__ = "GPLv2 - http://www.gnu.org/licenses/gpl-2.0.html"
